Cream of the Crop 1

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / SPAWNO41.ARJ / SPAWNO.DOC < prev next >

Wrap

Text File | 1992-04-26 | 21KB | 464 lines

SPAWNO v4.10 4/26/91 disk/EMS/XMS/INT15 swapping replacement for spawn() (c) Copyright 1990,1991,1992 Ralf Brown. All Rights Reserved. ----------------- LICENSE This document and the associated header file, libraries, and source and object modules may be freely copied provided that: 1) all of the files are copied as a group (such as in a single archive). See below for a list of files. 2) the files are not modified in any way (including removal or alteration of copyright notices or this license) 3) no charge beyond a cost-recovery fee not to exceed $5, or a general telecommunications connection fee, is made The source and/or object code comprising the public SPAWNO distribution may be incorporated at no charge into programs which are distributed or sold to others provided that: 1) credit is given in the documentation. A mention such as "This product uses the SPAWNO routines by Ralf Brown to minimize memory use while shelling to DOS and running other programs." is sufficient. 2) you drop me a line telling me that you are using SPAWNO and in which product(s) you are using it (see addresses at the end of this file). I'm interested in finding out how wide- spread the use of SPAWNO becomes. ----------------- DISCLAIMER Although both I and others have tested the code which comprises SPAWNO, it is entirely possible that SPAWNO may malfunction in environments or under circumstances in which it has not been tested. This code is provided AS IS, and the author disclaims any and all responsibility for damages (both consequential and incidental) resulting from the use or misuse of SPAWNO. Sole responsibility for determining the suitability of the code rests with the user. ----------------- FILES The disk or archive you received should contain the following files: SPAWNO.DOC this file SPAWNO.H the header file providing prototypes for the functions SPAWNx.LIB versions of the library for each of [T]iny, [S]mall, [C]ompact, [M]edium, [L]arge, and [H]uge memory models. SPAWNTP.OBJ Turbo Pascal version of SPAWNO SPAWNO.PAS Turbo Pascal unit encapsulating SPAWNO SPAWN_MS.ZIP Microsoft C versions of compiler-specific functions MSC.BAT replace Turbo C specific functions in libraries with Microsoft C versions. NOREPLAC.BAT remove replacements for the standard spawn..() functions from the libraries. SWAPTEST.C example program for testing TEST.PAS example program for testing SOURCE.ZIP archive containing partial source code for SPAWNO _SPAWNO.H header file for recompiling library *.C source for the spawn..() and spawn...o() functions RULES.ASI shortened and modified Turbo C macro file SPAWNO.INC include file for various important constants SPAWNPTH.ASM source for the path search CHECKEXT.ASM check for 'file', 'file.EXE', and 'file.COM' SWAP_EMS.ASM support routines for swapping to EMS SWAPLIST.ASM specify which swap types will be linked in SPAWNENV.ASM make an environment block from an array of strings SPAWNERR.ASM set _doserrno and errno MAKEFILE ----------------- WHAT'S NEW Changes/fixes since version 4.00: Now swaps to disk with non-NULL swap list in large-data memory models Now correctly deletes swap file if child program changes directories If the given program name is "FOO", and both "FOO" and either "FOO.COM" and/or "FOO.EXE" exist in the same directory, it will now execute either "FOO.COM" or "FOO.EXE" rather than "FOO", as both version 4.00 and the Borland library functions do. To execute "FOO", pass "FOO." rather than just "FOO" to the function. Fixed bug which may have led to a partially corrupted environment in a few circumstances ----------------- INSTALLATION If you are using Turbo C, Turbo C++, or Borland C++, simply dearchive the libraries and header file and place them where your compiler can find them. If you are using Microsoft C, dearchive SPAWN_MS.ZIP and then run the MSC batch file to replace the compiler-specific functions in the libraries with Microsoft C versions. Please do not run this batch file on your original copy of the libraries. If you are using Turbo Pascal, unarchive SPAWNTP.OBJ and SPAWNO.PAS. Compile SPAWNO.PAS and then add a USES SPAWNO; line to your program. After that you can call the function SPAWN() as desired. The distribution does not contain a pre-compiled version because .TPU files are not compatible between different versions of Turbo Pascal. ----------------- INSTRUCTIONS As distributed, SPAWNO contains replacements for the standard spawn..() functions. You can use SPAWNO with absolutely no changes to your existing source code; however, you will probably want to call init_SPAWNO() from main(), and include SPAWNO.H for that source file. The initialization function takes two arguments: the first is a string containing a list of directories (separated by semicolons) in which to attempt to store the swap file when swapping to disk. The second specifies which swap devices to attempt to use; it may be either SWAP_ANY or the ORing or addition of any combination of SWAP_DISK, SWAP_EMS, SWAP_EXT, and SWAP_XMS (such as SWAP_DISK|SWAP_XMS). If you do not call init_SPAWNO(), the defaults are to attempt all swap devices and to store the swap file in the current directory when swapping to disk. init_SPAWNO() will set the swap file directory list to the first of the following to have a non-NULL, non-empty value: the environment variable SWAPDIR, the passed parameter, the environment variable TEMP, and the environment variable TMP. Note that init_SPAWNO is the only function in the library which uses these environment variables. After making the above change, recompile your existing code, but include the SPAWNO library in the link step. Note that SPAWNO does not support the P_OVERLAY spawn type--any calls using that argument should be replaced with the corresponding exec..() function. If a SPAWNO function is called with P_OVERLAY, it simply returns an error. For backwards compatibility with previous versions of SPAWNO, and for those who (for whatever reason) require the use of both the swapping and standard spawn..() functions, there is a second set of functions which take an explicit swap directory argument. To use them, include the header file SPAWNO.H. Then use the functions provided in this archive--spawnvo(), spawnlo(), spawnvpo(), etc--as you would the corresponding spawnv(), spawnl(), etc, except replace the first argument by a string containing the path where the swap file is to be stored. Note that the swap file path is required even when swapping to XMS, EMS, or plain extended memory, as SPAWNO will swap to disk anyway if there is not enough memory available. If you require the use of both the swapping and standard spawn..() functions, you will need to run the NOREPLAC.BAT batch file to remove the modules containing the replacements for the standard functions or arrange the linker command line such that SPAWNx.LIB is listed after the standard runtime library (for Turbo/Borland C users, the latter requires a separate TLINK command, as TCC/BCC places any libraries specified on the command line prior to the runtime library). Please do not run NOREPLAC on your original copy of the libraries, as the process is destructive and cannot be reversed. The spawn?p??() functions search for both .COM and .EXE files in the current directory and then in the pathed directories if no extension is given, but use the specified extension if present. If a full pathname is given to those functions, only the specified directory is searched. If both a path and an extension are given, only that specific file will be loaded. The other spawn..() functions check the current directory only. For all functions, if the specified filename does not contain an extension, SPAWNO will try the exact name given and the name with .COM and .EXE extensions. The extension-less name will be used if neither .COM nor .EXE exist. To force the use of the extensionless file even if a .COM or .EXE with the same name exists in the same directory, append a period, i.e. use "PROGRAM." rather than just "PROGRAM" as the name. When linking, you must include SPAWNx.LIB. A sample TCC line would be tcc -mc <other-flags> sample spawnc.lib library.lib This results in 208 to 288 bytes remaining in memory (depending on swap type) while the spawned program executes. However, if you want to keep an interrupt hooked which might be invoked while spawned, you must set __spawn_resident large enough that *all* code and data which could be invoked by that interrupt is kept resident[1]. SPAWNO automatically deactivates INT 23h and INT 24h and restores them before returning to the caller unless __spawn_keepints is set to 1, so no extra work is required if those two are the only interrupts hooked by the program. ---- [1] Due to the segment layout used by C compilers, this option is probably useful only when calling SPAWNO from assembly-language code (which can localize such code and data near the start of the executable) or a small program which uses a large amount of space in the far heap. ----------------- ERROR MESSAGES SPAWNO: stack too small, retrying SPAWNO did not correctly determine the stack requirements for the system on which it is running, but was able to determine that the specified minimum size is insufficient. On the retry, the stack size is increased by one paragraph. Since SPAWNO cannot always detect the problem, which would result in memory chain corruption, you should increase the value of __spawn_res_stack to prevent a recurrence of this error message. For most systems, the default value of 4 paragraphs will be sufficient. SWAP ERR The resident stub detected an error while trying to reload the main portion of the program and aborted. This may be due to loading a TSR while swapped out or deleting the swap file. SPAWNO: error reloading program, aborting The main portion of SPAWNO detected an error while attempting to restore the remainder of the program to memory. ----------------- LIMITATIONS After freeing all memory owned by the program except the initial (PSP) memory block and the environment, at least 384 bytes of conventional memory must be available. SPAWNO uses this for its temporary stack. This is of particular importance for the Turbo Pascal variant, because setting the maximum heap size to the available memory or greater will use up all RAM and prevent SPAWNO from allocating its temporary stack unless memory is fragmented or there is DOS 5 high memory available. SPAWNO may report insufficient memory even though the program to be executed would fit with up to 600 bytes to spare, due to the fact that part of the stack and all of the data used by DOS to start the program may be overwritten after the child program starts executing. Functions which pass an explicit environment attempt to allocate enough memory to build the environment block which is passed to the DOS EXEC function. If neither malloc() nor a DOS memory allocation request are successful, SPAWNO passes the original environment rather than the specified environment. As distributed, SPAWNO functions which do not take an explicit environment pointer pass the calling program's original environment to the child, rather than the current environment as modified by putenv(). You may recompile SPAWNO to pass the current environment (see _SPAWNO.H); if you do so, the caveat discussed in the previous paragraph will apply to all of the spawn..() functions. ----------------- SUPPORT Since I am not getting any money, I can't promise any support. Those who have purchased the complete source code will receive priority over those who haven't, but even they will only receive support to the extent that I have spare time.... ----------------- ACKNOWLEDGEMENTS Thanks to Gene McManus for testing the Microsoft versions of SPAWNO 3.0 and 4.0. ----------------- FUTURE PLANS The next release will drop support for DOS 2.x (which is now over seven years old) to reduce the code size and further reduce the size of the resident stub. ----------------- SPAWNO versus THE COMPETITION Product: SPAWNO XSPAWN SWAP Version: 4.02 1.34 1.0 Author: Ralf Brown Whitney Software Marty Del Vecchio Memory models: tsmclh tsmclh tsm Supported DOS vers: 2.0-5.0 2.1-5.0 3.0-5.0 Code size [1]: 4.2-5.6K 4.4-9K 1.5K Resident stub (bytes): 208-288 1277+2*env 1.8K+env [2] Direct replacement for spawn..(): yes yes no Use in existing code without changes: yes no no Swap to disk: yes yes yes Swap to EMS: yes yes yes Swap to XMS: yes no no Swap to INT 15h ext: yes no no Multiple swap dirs: yes yes no Automatic unique swap file naming: yes yes no May leave interrupts hooked [3]: yes no yes Swaps DOS5 high memory: yes ? ? Free for any use: yes yes yes Source included: partial [4] yes yes Notes: [1] For both SPAWNO and XSPAWN, the amount added to the executable's size depends on which functions of the library are called and which of the additional C runtime library function that are called by SPAWNO/XSPAWN would have been included anyway. SPAWNO's size may be reduced by removing one or more swap types; the savings are about 400 bytes per swap type (without EMS and non-XMS (INT 15h) swapping, SPAWNO would add as little as 3.4K to the executable). [2] SWAP's resident size depends on the location of the object code within the executable. The size reported here is the resident size when SWAP immediately follows the Turbo C 2.0 startup code. [3] For SPAWNO, enough of the program must be left in memory to keep all interrupt handlers resident. XSPAWN has no provision for keeping an interrupt handler resident unless swapping is disabled; it does however permit selection whether a given interrupt handler will automatically be restored to its original value or pointed at an IRET instruction while swapped out. For SWAP, the swapper module must be linked in after all code and data which might be accessed by the interrupt handler(s). [4] Full SPAWNO source code is available for purchase. See ORDER.FRM for details. ----------------- Functions: void init_SPAWNO(const char *swap_directories, int swap_types) ; /* replacements for the standard functions */ int spawnv(int type, const char *name, const char **args) ; int spawnvp(int type, const char *name, const char **args) ; int spawnve(int type, const char *name, const char **args, const char **env) ; int spawnvpe(int type, const char *name, const char **args, const char **env) ; int spawnl(int type, const char *name, const char *argv0, ...) ; int spawnlp(int type, const char *name, const char *argv0, ...) ; int spawnle(int type, const char *name, const char *argv0, ...) ; int spawnlpe(int type, const char *name, const char *argv0, ...) ; int system(const char *command) ; /* Note: the above functions return -1 (error) if 'type' is not */ /* P_WAIT */ /* setup function */ void init_SPAWNO(const char *overlay_path, int swap_types) ; /* setup swapping options for the compatibility functions above */ /* SPAWNO-specific functions */ int spawnvo(const char *overlay_path, const char *name, const char **args) ; int spawnvpo(const char *overlay_path, const char *name, const char **args) ; int spawnveo(const char *overlay_path, const char *name, const char **args,const char **env) ; int spawnvpeo(const char *overlay_path, const char *name, const char **args,const char **env) ; int spawnlo(const char *overlay_path, const char *name, ...) ; int spawnlpo(const char *overlay_path, const char *name, ...) ; int spawnleo(const char *overlay_path, const char *name, ...) ; int spawnlpeo(const char *overlay_path, const char *name, ...) ; int systemo(const char *overlay_path, const char *command) ; /* Note: the ..o() functions use the current directory only if */ /* overlay_path is NULL; the only function which checks */ /* the environment variables SWAPDIR and TEMP is */ /* init_SPAWNO(). */ Global variables: char __spawn_xms ; Specify whether to use XMS memory for swapping (if available). 0 = no, 1 = yes, default = 1 This variable is set by init_SPAWNO(). char __spawn_ems ; Specify whether to use EMS memory for swapping (if available). 0 = no, 1 = yes, default = 1 This variable is set by init_SPAWNO(). char __spawn_ext ; /* 0 = don't use non-XMS extended memory for swap */ Specify whether to use non-XMS extended memory (via INT 15h) for swapping (if available). 0 = no, 1 = yes, default = 1 This variable is set by init_SPAWNO(). Note: SPAWNO should not be allowed to swap to extended memory if running under a multitasker or task switcher, as other programs would be able to grab the same memory used by SPAWNO to store the swapped-out program. For this reason, SPAWNO automatically disables swapping to non-XMS extended memory if it detects that TopView, DESQview, or any other TopView API-compatible multi- tasker is active, or the DOS 5 task switcher is loaded, or MS Windows 3 is running in real or standard mode (enhanced mode is not readily detectable from a program, unfortunately). const char *pascal ___spawn_swap_dirs ; Specify the list of directories in which to attempt to store the swap file when swapping to disk. The directories are separated by semicolons just as they would be in the PATH environment variable. Default = "." (current directory) This variable is set by init_SPAWNO(). Note: SPAWNO will not swap to disk if this variable is set to an empty string; if it is set to NULL, SPAWNO will use the default of ".". char __spawn_keepints ; Specify whether to deactivate INT 23h and INT 24h handlers by temporarily restoring the vectors stored in the PSP. 0 = no, nonzero = yes, default = 0 char __spawn_swap_UMA ; Specify whether to swap out memory blocks in the upper memory area (640K-1M). 0 = no, 1 = yes, default = 1 Note: This option only has an effect under MSDOS 5.0 with the line DOS=UMB or DOS=HIGH,UMB in CONFIG.SYS. unsigned __spawn_resident ; Specify the minimum number of paragraphs in the memory block containing the PSP to keep resident while in the child program. This value will be increased if necessary to be large enough to hold the swapping code; it may also be increased slightly if it causes the end of the shrunken PSP block to fall within a specific section of SPAWNO's code. You may force the entire main block to stay in memory by setting this variable to 0xFFFF; however, the environment and any additional memory blocks allocated by the program will still be swapped out. default = 0 Note: in addition to the PSP memory block, a small second block is used for the stack needed by the swapping code (see below). unsigned __spawn_res_stack ; Specify the minimum number of paragraphs of the stack to keep resident while in the child program. Default = 4, minimum = 2 (two paragraphs is only sufficient for bare DOS; TSRs which hook INT 21h will increase the stack requirements, but four is sufficient for most systems). SPAWNO attempts to compute the necessary stack size, but this variable allows the computed value to be overridden if necessary. External functions called by SPAWNO: malloc() \ only when passing an array of environment strings free() / External variables referenced by SPAWNO: int errno ; int _doserrno ; unsigned int _psp ; char **environ ; (only when passing an array of environment strings) Other: This version of SPAWNO overwrites the PSP, so the commandline will be lost unless it was copied before the first spawn(). ----------------- Functions (Turbo Pascal): init_SPAWNO(swap_dirs : string ; swap_types : integer ; min_resident : integer ; resident_stack : integer) ; spawn(program_name : string ; arguments : string ; envseg : integer) : integer ; Global Variables (Turbo Pascal): spawno_error : integer ; (error code when spawn() returns -1) ----------------- Send comments, bug reports, etc. to Internet: ralf+@cs.cmu.edu Fidonet: Ralf Brown 1:129/26.1 (or post a message to me on DR_DEBUG--I have to route netmail outside Zone 1 via Internet -> Fidonet gateways, which is not always reliable) or Ralf Brown Suite #26 813 Copeland Way Pittsburgh, PA 15232